// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

part of dart.core;

/**
 * 所有堆栈轨迹对象实现的接口。
 *
 * [StackTrace]的目的是将引发异常的调用序列的信息传达给使用者。
 *
 * 这些对象在运行时被创建，并且在编程时是不可能被创建的。
 */
abstract class StackTrace {
  StackTrace();  // In case existing classes extend StackTrace.

  /**
   * 从[stackTraceString]创建`StackTrace`对象。
   *
   * 创建的对象使用`toString`方法将返回`stackTraceString`。
   *
   * `stackTraceString`可以是其它堆栈轨迹对象返回的字符串，也可以是任何的字符串。
   * 如果字符串看起来并不像堆栈轨迹，代码在解释轨迹的时候可能会失败。
   * 因此，伪堆栈轨迹应该谨慎使用。
   */
  factory StackTrace.fromString(String stackTraceString) = _StringStackTrace;

  /**
   * 返回当前堆栈轨迹。
   *
   * 可以通过类似下面的代码实现：
   *
   *     try { throw 0; } catch (_, stack) { return stack; }
   *
   * 在平台没有其它的方法得到堆栈轨迹时，可以使用getter方法获取该值，
   * 因为它不会抛出任何异常/错误。
   */
  external static StackTrace get current;

  /**
   * 返回一个用来表示堆栈轨迹的字符串。
   *
   * 字符串表示完整的堆栈轨迹，从throw发生的位置到当前调用序列的顶部。
   *
   * 字符串确切的格式并不是最终的、不可更改的。
   */
  String toString();
}

class _StringStackTrace implements StackTrace {
  final String _stackTrace;
  _StringStackTrace(this._stackTrace);
  String toString() => _stackTrace;
}
